home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / AppleGuide.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  10KB  |  362 lines
  1. /*
  2.      File:        AppleGuide.h
  3.  
  4.      Contains:    Apple Guide Interfaces.
  5.  
  6.      Version:    Technology:    System 7.5
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __APPLEGUIDE__
  19. #define __APPLEGUIDE__
  20.  
  21. #ifndef __APPLEEVENTS__
  22. #include <AppleEvents.h>
  23. #endif
  24. #ifndef __FILES__
  25. #include <Files.h>
  26. #endif
  27. #ifndef __TYPES__
  28. #include <Types.h>
  29. #endif
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35. #if PRAGMA_IMPORT_SUPPORTED
  36. #pragma import on
  37. #endif
  38.  
  39. #if PRAGMA_ALIGN_SUPPORTED
  40. #pragma options align=mac68k
  41. #endif
  42.  
  43. #if FOR_SYSTEM7_AND_SYSTEM8_COOPERATIVE
  44. /* Types*/
  45. typedef UInt32 AGRefNum;
  46. typedef UInt32 AGCoachRefNum;
  47. typedef UInt32 AGContextRefNum;
  48. struct AGAppInfo {
  49.     AEEventID                         eventId;
  50.     long                             refCon;
  51.     void *                            contextObj;                    /* private system field*/
  52. };
  53. typedef struct AGAppInfo AGAppInfo;
  54.  
  55. typedef AGAppInfo *AGAppInfoPtr;
  56. typedef AGAppInfoPtr *AGAppInfoHdl;
  57. typedef pascal OSErr (*CoachReplyProcPtr)(Rect *pRect, Ptr name, long refCon);
  58. typedef pascal OSErr (*ContextReplyProcPtr)(Ptr pInputData, Size inputDataSize, Ptr *ppOutputData, Size *pOutputDataSize, AGAppInfoHdl hAppInfo);
  59.  
  60. #if GENERATINGCFM
  61. typedef UniversalProcPtr CoachReplyUPP;
  62. typedef UniversalProcPtr ContextReplyUPP;
  63. #else
  64. typedef CoachReplyProcPtr CoachReplyUPP;
  65. typedef ContextReplyProcPtr ContextReplyUPP;
  66. #endif
  67.  
  68. enum {
  69.     uppCoachReplyProcInfo = kPascalStackBased
  70.          | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
  71.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(Rect *)))
  72.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(Ptr)))
  73.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(long))),
  74.     uppContextReplyProcInfo = kPascalStackBased
  75.          | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
  76.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(Ptr)))
  77.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(Size)))
  78.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(Ptr *)))
  79.          | STACK_ROUTINE_PARAMETER(4, SIZE_CODE(sizeof(Size *)))
  80.          | STACK_ROUTINE_PARAMETER(5, SIZE_CODE(sizeof(AGAppInfoHdl)))
  81. };
  82.  
  83. #if GENERATINGCFM
  84. #define NewCoachReplyProc(userRoutine)        \
  85.         (CoachReplyUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppCoachReplyProcInfo, GetCurrentArchitecture())
  86. #define NewContextReplyProc(userRoutine)        \
  87.         (ContextReplyUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppContextReplyProcInfo, GetCurrentArchitecture())
  88. #else
  89. #define NewCoachReplyProc(userRoutine)        \
  90.         ((CoachReplyUPP) (userRoutine))
  91. #define NewContextReplyProc(userRoutine)        \
  92.         ((ContextReplyUPP) (userRoutine))
  93. #endif
  94.  
  95. #if GENERATINGCFM
  96. #define CallCoachReplyProc(userRoutine, pRect, name, refCon)        \
  97.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppCoachReplyProcInfo, (pRect), (name), (refCon))
  98. #define CallContextReplyProc(userRoutine, pInputData, inputDataSize, ppOutputData, pOutputDataSize, hAppInfo)        \
  99.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppContextReplyProcInfo, (pInputData), (inputDataSize), (ppOutputData), (pOutputDataSize), (hAppInfo))
  100. #else
  101. #define CallCoachReplyProc(userRoutine, pRect, name, refCon)        \
  102.         (*(userRoutine))((pRect), (name), (refCon))
  103. #define CallContextReplyProc(userRoutine, pInputData, inputDataSize, ppOutputData, pOutputDataSize, hAppInfo)        \
  104.         (*(userRoutine))((pInputData), (inputDataSize), (ppOutputData), (pOutputDataSize), (hAppInfo))
  105. #endif
  106. /* Constants*/
  107.  
  108. enum {
  109.     kAGDefault                    = 0,
  110.     kAGFrontDatabase            = 1,
  111.     kAGNoMixin                    = (-1)
  112. };
  113.  
  114.  
  115. enum {
  116.     kAGViewFullHowdy            = 1,                            /* Full-size Howdy*/
  117.     kAGViewTopicAreas            = 2,                            /* Full-size Topic Areas*/
  118.     kAGViewIndex                = 3,                            /* Full-size Index Terms*/
  119.     kAGViewLookFor                = 4,                            /* Full-size Look-For (Search)*/
  120.     kAGViewSingleHowdy            = 5,                            /* Single-list-size Howdy*/
  121.     kAGViewSingleTopics            = 6                                /* Single-list-size Topics*/
  122. };
  123.  
  124.  
  125. enum {
  126.     kAGFileMain                    = 'poco',
  127.     kAGFileMixin                = 'mixn'
  128. };
  129.  
  130. /* To test against AGGetAvailableDBTypes*/
  131.  
  132. enum {
  133.     kAGDBTypeBitAny                = 0x00000001,
  134.     kAGDBTypeBitHelp            = 0x00000002,
  135.     kAGDBTypeBitTutorial        = 0x00000004,
  136.     kAGDBTypeBitShortcuts        = 0x00000008,
  137.     kAGDBTypeBitAbout            = 0x00000010,
  138.     kAGDBTypeBitOther            = 0x00000080
  139. };
  140.  
  141. typedef UInt16 AGStatus;
  142. /* Returned by AGGetStatus*/
  143.  
  144. enum {
  145.     kAGIsNotRunning                = 0,
  146.     kAGIsSleeping                = 1,
  147.     kAGIsActive                    = 2
  148. };
  149.  
  150. typedef UInt16 AGWindowKind;
  151. /* Returned by AGGetFrontWindowKind*/
  152.  
  153. enum {
  154.     kAGNoWindow                    = 0,
  155.     kAGAccessWindow                = 1,
  156.     kAGPresentationWindow        = 2
  157. };
  158.  
  159. /*
  160.  Error Codes
  161.  Not an enum, because other OSErrs are valid.
  162. */
  163. typedef SInt16 AGErr;
  164. /* Apple Guide error codes*/
  165.  
  166. enum {
  167.                                                                 /* -------------------- Apple event reply codes*/
  168.     kAGErrUnknownEvent            = -2900,
  169.     kAGErrCantStartup            = -2901,
  170.     kAGErrNoAccWin                = -2902,
  171.     kAGErrNoPreWin                = -2903,
  172.     kAGErrNoSequence            = -2904,
  173.     kAGErrNotOopsSequence        = -2905,
  174.     kAGErrReserved06            = -2906,
  175.     kAGErrNoPanel                = -2907,
  176.     kAGErrContentNotFound        = -2908,
  177.     kAGErrMissingString            = -2909,
  178.     kAGErrInfoNotAvail            = -2910,
  179.     kAGErrEventNotAvailable        = -2911,
  180.     kAGErrCannotMakeCoach        = -2912,
  181.     kAGErrSessionIDsNotMatch    = -2913,
  182.     kAGErrMissingDatabaseSpec    = -2914,                        /* -------------------- Coach's Chalkboard reply codes*/
  183.     kAGErrItemNotFound            = -2925,
  184.     kAGErrBalloonResourceNotFound = -2926,
  185.     kAGErrChalkResourceNotFound    = -2927,
  186.     kAGErrChdvResourceNotFound    = -2928,
  187.     kAGErrAlreadyShowing        = -2929,
  188.     kAGErrBalloonResourceSkip    = -2930,
  189.     kAGErrItemNotVisible        = -2931,
  190.     kAGErrReserved32            = -2932,
  191.     kAGErrNotFrontProcess        = -2933,
  192.     kAGErrMacroResourceNotFound    = -2934,                        /* -------------------- API reply codes*/
  193.     kAGErrAppleGuideNotAvailable = -2951,
  194.     kAGErrCannotInitCoach        = -2952,
  195.     kAGErrCannotInitContext        = -2953,
  196.     kAGErrCannotOpenAliasFile    = -2954,
  197.     kAGErrNoAliasResource        = -2955,
  198.     kAGErrDatabaseNotAvailable    = -2956,
  199.     kAGErrDatabaseNotOpen        = -2957,
  200.     kAGErrMissingAppInfoHdl        = -2958,
  201.     kAGErrMissingContextObject    = -2959,
  202.     kAGErrInvalidRefNum            = -2960,
  203.     kAGErrDatabaseOpen            = -2961,
  204.     kAGErrInsufficientMemory    = -2962
  205. };
  206.  
  207. /*
  208.  Events
  209.  Not an enum because we want to make assignments.
  210. */
  211. typedef UInt32 AGEvent;
  212. /* Handy events for AGGeneral.*/
  213.  
  214. enum {
  215.                                                                 /* Panel actions (Require a presentation window).*/
  216.     kAGEventDoCoach                = 'doco',
  217.     kAGEventDoHuh                = 'dhuh',
  218.     kAGEventGoNext                = 'gonp',
  219.     kAGEventGoPrev                = 'gopp',
  220.     kAGEventHidePanel            = 'pahi',
  221.     kAGEventReturnBack            = 'gobk',
  222.     kAGEventShowPanel            = 'pash',
  223.     kAGEventTogglePanel            = 'patg'
  224. };
  225.  
  226. /*
  227.  Functions
  228.  AGClose
  229.  Close the database associated with the AGRefNum.
  230. */
  231. extern pascal AGErr AGClose(AGRefNum *refNum)
  232.  TWOWORDINLINE(0x7011, 0xAA6E);
  233.  
  234. /*
  235.  AGGeneral
  236.  Cause various events to happen.
  237. */
  238. extern pascal AGErr AGGeneral(AGRefNum refNum, AGEvent theEvent)
  239.  TWOWORDINLINE(0x700D, 0xAA6E);
  240.  
  241. /*
  242.  AGGetAvailableDBTypes
  243.  Return the database types available for this application.
  244. */
  245. extern pascal UInt32 AGGetAvailableDBTypes(void )
  246.  TWOWORDINLINE(0x7008, 0xAA6E);
  247.  
  248. /*
  249.  AGGetFrontWindowKind
  250.  Return the kind of the front window.
  251. */
  252. extern pascal AGWindowKind AGGetFrontWindowKind(AGRefNum refNum)
  253.  TWOWORDINLINE(0x700C, 0xAA6E);
  254.  
  255. /*
  256.  AGGetFSSpec
  257.  Return the FSSpec for the AGRefNum.
  258. */
  259. extern pascal AGErr AGGetFSSpec(AGRefNum refNum, FSSpec *fileSpec)
  260.  TWOWORDINLINE(0x700F, 0xAA6E);
  261.  
  262. /*
  263.  AGGetStatus
  264.  Return the status of Apple Guide.
  265. */
  266. extern pascal AGStatus AGGetStatus(void )
  267.  TWOWORDINLINE(0x7009, 0xAA6E);
  268.  
  269. /*
  270.  AGInstallCoachHandler
  271.  Install a Coach object location query handler.
  272. */
  273. extern pascal AGErr AGInstallCoachHandler(CoachReplyUPP coachReplyProc, long refCon, AGCoachRefNum *resultRefNum)
  274.  TWOWORDINLINE(0x7012, 0xAA6E);
  275.  
  276. /*
  277.  AGInstallContextHandler
  278.  Install a context check query handler.
  279. */
  280. extern pascal AGErr AGInstallContextHandler(ContextReplyUPP contextReplyProc, AEEventID eventID, long refCon, AGContextRefNum *resultRefNum)
  281.  TWOWORDINLINE(0x7013, 0xAA6E);
  282.  
  283. /*
  284.  AGIsDatabaseOpen
  285.  Return true if the database associated with the AGRefNum is open.
  286. */
  287. extern pascal Boolean AGIsDatabaseOpen(AGRefNum refNum)
  288.  TWOWORDINLINE(0x7006, 0xAA6E);
  289.  
  290. /*
  291.  AGOpen
  292.  Open a guide database.
  293. */
  294. extern pascal AGErr AGOpen(FSSpec *fileSpec, UInt32 flags, Handle mixinControl, AGRefNum *resultRefNum)
  295.  TWOWORDINLINE(0x7001, 0xAA6E);
  296.  
  297. /*
  298.  AGOpenWithSearch
  299.  Open a guide database and preset a search string.
  300. */
  301. extern pascal AGErr AGOpenWithSearch(FSSpec *fileSpec, UInt32 flags, Handle mixinControl, ConstStr255Param searchString, AGRefNum *resultRefNum)
  302.  TWOWORDINLINE(0x7002, 0xAA6E);
  303.  
  304. /*
  305.  AGOpenWithSequence
  306.  Open a guide database and display a presentation window sequence.
  307. */
  308. extern pascal AGErr AGOpenWithSequence(FSSpec *fileSpec, UInt32 flags, Handle mixinControl, short sequenceID, AGRefNum *resultRefNum)
  309.  TWOWORDINLINE(0x7004, 0xAA6E);
  310.  
  311. /*
  312.  AGOpenWithView
  313.  Open a guide database and override the default view.
  314. */
  315. extern pascal AGErr AGOpenWithView(FSSpec *fileSpec, UInt32 flags, Handle mixinControl, short viewNum, AGRefNum *resultRefNum)
  316.  TWOWORDINLINE(0x7005, 0xAA6E);
  317.  
  318. /*
  319.  AGQuit
  320.  Make Apple Guide quit.
  321. */
  322. extern pascal AGErr AGQuit(void )
  323.  TWOWORDINLINE(0x7010, 0xAA6E);
  324.  
  325. /*
  326.  AGRemoveCoachHandler
  327.  Remove the Coach object location query handler.
  328. */
  329. extern pascal AGErr AGRemoveCoachHandler(AGCoachRefNum *resultRefNum)
  330.  TWOWORDINLINE(0x7014, 0xAA6E);
  331.  
  332. /*
  333.  AGRemoveContextHandler
  334.  Remove the context check query handler.
  335. */
  336. extern pascal AGErr AGRemoveContextHandler(AGContextRefNum *resultRefNum)
  337.  TWOWORDINLINE(0x7015, 0xAA6E);
  338.  
  339. /*
  340.  AGStart
  341.  Start up Apple Guide in the background.
  342. */
  343. extern pascal AGErr AGStart(void )
  344.  TWOWORDINLINE(0x700A, 0xAA6E);
  345.  
  346. #endif
  347.  
  348. #if PRAGMA_ALIGN_SUPPORTED
  349. #pragma options align=reset
  350. #endif
  351.  
  352. #if PRAGMA_IMPORT_SUPPORTED
  353. #pragma import off
  354. #endif
  355.  
  356. #ifdef __cplusplus
  357. }
  358. #endif
  359.  
  360. #endif /* __APPLEGUIDE__ */
  361.  
  362.